Flagging Issues in Text

Sapling's API and SDK can be used in a variety of different ways to process text and automatically flag issues. These can range from grammatical mistakes to making writing more confident, concise, or inclusive.

We list some of the issues that you can flag in your text as part of a processing pipeline, or integrated into an application that acts as an AI writing assistant for your users. To get started, you'll need to generate an API key following the steps here.

Contents

1. Spell Checking
2. Grammar Issues
3. Advanced Edits
4. AI Content Detection
5. Tone Issues
6. Diversity, Equity and Inclusion (DEI)

Spell Checking

Spell checking is the quickest and cheapest API endpoint for flagging issues in text. You can check this page to see which languages are supported: /docs/api/spellcheck.

If you are looking to add spell checking functionality to a website or web application, you can use the JavaScript SDK.

Sample Code

import requests

key = '<api-key>'

url = 'https://api.sapling.ai/api/v1/spellcheck'
data = {
    'key': key,
    'text': 'Here is a recomendation.',
    'session_id': 'Test Document UUID',
}

resp = requests.post(url, json=data)
resp_json = resp.json()
print('Edits: ', resp_json['edits'])

Sample Output

[{
    "id": "c7a85578-2391-5d9e-81b5-fc5c1574d07a",
    "replacement": "recommendation",
    "sentence": "Here is a recomendation.",
    "sentence_start": 0,
    "start": 10,
    "end": 23
}]

Grammar Issues

Sapling can help suggest edits around grammatical errors and ensure that your writing is idiomatic and fluent.

Check http://sapling.ai/docs/api/edits-overview to see which languages are supported.

If you are looking to add grammar checking functionality to a website or web application, you can use the JavaScript SDK.

Sample Code

import requests

key = '<api-key>'

url = 'https://api.sapling.ai/api/v1/edits'
data = {
    'key': key,
    'text': 'Lets get started!',
    'session_id': 'Test Document UUID',
}

resp = requests.post(url, json=data)
resp_json = resp.json()
print('Edits: ', resp_json['edits'])

Sample Output

[{
    "error_type": "R:OTHER",
    "general_error_type": "Other",
    "id": "aa5ee291-a073-5146-8ebc-c9c899d01278",
    "replacement": "Let's",
    "sentence": "Lets get started!",
    "sentence_start": 0,
    "start": 0
    "end": 4,
}]

Advanced Edits

This is a category of writing suggestions that go beyond regular grammatical correctness. Advanced Edits are a set of more opionated recommendations for effective written communication. These suggestions may make more sense applied to a press release or a business email compared to a creative novel.

Below is a list of configurable advanced edits categories and corresponding examples:

Adverbs

Adverbs can usually be replaced either with a stronger verb.

He ran quickly towards the exit. -> He dashed towards the exit.

Simplifications

Consider replacing complex phrases with a simpler one with the same meaning.

A number of people feel this way. -> Many people feel this way.

Hard to read

Sentences that are too long can be hard to read. Consider breaking them up for clarity.

In the age of digital technology and social media, it's becoming increasingly important for individuals to be aware of their online presence and the impact that their actions and words can have on others.

->

In the digital age, it's vital to be aware of how our online presence and actions can impact others.

Passive Voice

Sentences in the active voice are usually more concise and clear.

The ball was kicked by him. -> He kicked the ball.

Qualifiers

Qualifiers lead to less confident communication. Consider removing them.

I was wondering if we can meet tomorrow? -> Can we meet tomorrow?

You can find a demo of advanced edits here.

cURL

curl -X POST https://api.sapling.ai/api/v1/edits \
     -H "Content-Type: application/json" \
     -d '{
        "key":"<api-key>",
        "text":"The ball was kicked. Suddenly there was the sound of an aircraft.",
        "session_id": "test session",
        "advanced_edits": { "advanced_edits": true }
    }'

JavaScript

import axios from 'axios';

async function run(text) {
    try {
        const response = await axios.post(
            'https://api.sapling.ai/api/v1/edits',
            {
                key: '<api-key>',
                session_id: 'test session',
                text,
                advanced_edits: {
                    advanced_edits: true,
                },
            },
        );
        const {status, data} = response;
        console.log({status});
        console.log(JSON.stringify(data, null, 4));
    } catch (err) {
        const { msg } = err.response.data;
        console.log({err: msg});
    }
}

run('The ball was kicked. Suddenly there was the sound of an aircraft.');

Python

import requests
from pprint import pprint

key = '<api-key>'
url = 'https://api.sapling.ai/api/v1/edits'

data = {
    'key': key,
    'text': 'The ball was kicked. Suddenly there was the sound of an aircraft.',
    'session_id': 'Test Document UUID',
    'advanced_edits': {
        'advanced_edits': True,
    },
}

try:
    response = requests.post(url, json=data)
    resp_json = response.json()
    if 200 <= response.status_code < 300:
      edits = resp_json['edits']
      pprint(edits)
    else:
      print('Error: ', resp_json)
except Exception as e:
    print('Error: ', e)

Sample Response

[
    {
        "description": "Reduce the use of passive voice.",
        "end": 19,
        "error_type": "voice",
        "general_error_type": "Advanced Edit",
        "id": "81695ccc-2916-50ba-8b93-c3ed7bb55f54",
        "replacement": "",
        "sentence": "The ball was kicked.",
        "sentence_start": 0,
        "start": 9
    },
    {
        "description": "Reduce the use of adverbs.",
        "end": 8,
        "error_type": "adverbs",
        "general_error_type": "Advanced Edit",
        "id": "62cb63df-7c3d-52de-aab2-eded6924d689",
        "replacement": "",
        "sentence": "Suddenly there was the sound of an aircraft.",
        "sentence_start": 21,
        "start": 0
    },
    {
        "description": "Use simpler language where possible.",
        "end": 43,
        "error_type": "simplifications",
        "general_error_type": "Advanced Edit",
        "id": "a0367693-de21-524f-9a3e-abe7a62b46f6",
        "replacement": "plane",
        "sentence": "Suddenly there was the sound of an aircraft.",
        "sentence_start": 21,
        "start": 35
    }
]

AI Content

The AI Content detector can be used to flag sentences or sections of text that were likely to have been generated by an AI language model. Depending on how the text is being used, AI content may not be allowed for legal, educational or regulatory reasons. Using an AI content detector can help reduce the costs of detecting such content. Details on the AI Content Detection API can be found here.

Sample Code

import requests
from pprint import pprint

key = '<api-key>'

url = 'https://api.sapling.ai/api/v1/aidetect'
data = {
    'key': key,
    'text': 'I am an artificial intelligence system designed to help people solve complex problems. My capabilities include natural language processing, machine learning, and predictive analytics.',
}

try:
    response = requests.post(url, json=data)
    resp_json = response.json()
    if 200 <= response.status_code < 300:
        edits = resp_json['edits']
        pprint(edits)
    else:
        print('Error: ', resp_json)
except Exception as e:
    print('Error: ', e)

Sample Output

{
  "score":0.9989707556330055,
  "sentence_scores":[
    {
      "score":0.9764397893790885,
      "sentence": "I am an artificial intelligence system designed to help people solve complex problems."
    },
    {
      "score":0.9923806397189778,
      "sentence":"My capabilities include natural language processing, machine learning, and predictive analytics."
    }
  ],
  "text":"I am an artificial intelligence system designed to help people solve complex problems. My capabilities include natural language processing, machine learning, and predictive analytics."
}

Tone

Tone analysis is done on an overall level as well as on a per sentence level. We flag negative passages of text that could be interpreted negatively for review. If you or your users want to avoid coming off as angry or disapproving, this endpoint can help. More details on the tone api and all the tones classified can be found here.

Here is an example of how the Tone API is used in the Sapling browser extension. Note how the negative sentence is highlighted.

This is an example of another UI component from the Sapling tone checker. You can display the overal analyzed tone of a piece of text.

Sample Code

import requests

key = '<api-key>'
url = 'https://api.sapling.ai/api/v1/tone'

data = {
    'key': key,
    'text': 'You are amazing',
}

resp = requests.post(url, json=data)
print(resp.json())

Sample Output

{
    "overall": [
        [0.8885115385055542, "admiring", "😲"],
        [0.06413709372282028, "excited", "😀"],
        [0.02678699605166912, "approving", "👍"]
    ],
    "results": [
        [
            [0.8885115385055542, "admiring", "😲"],
            [0.06413709372282028, "excited", "😀"],
            [0.02678699605166912, "approving", "👍"]
        ]
    ],
    "sents": ["You are amazing"]
}

Diversity, Equity and Inclusion (DEI)

When writing in a way that is "DEI", we want to respect the linguistic viewpoints and cultures of different people. Inclusion in language refers to treating people with respect and making them feel included. While there is no absolute standard for DEI language, we can always avoid using certain terms that are considered racist or derogatory towards disadvantaged groups of people.

Sapling breaks DEI into the following categories. Example of each are also given:

• Gender Pronouns

  Prefer "they"/"them" over "he"/"him"

• Gender Nouns

  Prefer "chairperson" over "chairman"

• Gender Identity

  Prefer "transgender" over "transexual"

• Disability

  Prefer "autistic" over "aspie"

• Age

  Prefer "person born betwen 1946-1964" over "boomer"

• Race

  Prefer "primary-secondary" over "master-slave"

• Social Class

  Prefer "sex worker" over "prostitute"

• Violence Prefer "situation room" over "war room"

You can fine-tune your DEI settings in the language settings dashboard here: https://sapling.ai/language_settings. A demo of DEI checking can be found here.

Sample Code

import requests

key = '<api-key>'
url = 'https://api.sapling.ai/api/v1/edits'

data = {
    'key': key,
    'text': 'This is the master bedroom.',
    'session_id': 'Test Document UUID',
    'advanced_edits': {
        'dei': True,
    },
}

try:
    resp = requests.post(url, json=data)
    resp_json = resp.json()
    if 200 <= resp.status_code < 300:
      edits = resp_json['edits']
      print('Edits: ', edits)
    else:
      print('Error: ', resp_json)
except Exception as e:
    print('Error: ', e)

Sample Output

[
    {
        "description": "Use more inclusive language where possible.",
        "end": 18,
        "error_type": "dei",
        "general_error_type": "Advanced Edit",
        "id": "fa409ba8-a51c-5d9e-b007-1bde1ac6183a",
        "replacement": "primary",
        "sentence": "This is the master bedroom.",
        "sentence_start": 0,
        "start": 12
    }
]